OpenHR 20 Tutorial: Part 0 – Introduction

What is HR-20?

Honeywell HR-20 is an electronic programmable thermostat made by – well, Honeywell. You can read more about it on its homepage. Its main feature is that you can program 2 temperature settings and a time schedule, which can change your temperature 4 times a day to one of the preset temperatures. You can also have a separate schedule for every day of the week. Other than that, it offers freeze protection and automatic open window detection.

Honeywell HR-20 electronic thermostat

Because some of that features are limiting and some bugs were found in the original firmware, a group of electronics hackers reverse engineered the thermostat and wrote open source version of the thermostat’s firmware – and that’s OpenHR20. Since HR20’s main controller is an ATmega169p, it is quite easy to modify and program the firmware. OpenHR20 gives you 4 temperature settings, 8 temperature change timers and a control and monitoring protocol that runs over TTL serial on the diagnostic connection of the thermostat. It also fixes some issues with original firmware, like opened window detection or “cold valve” problem. Also, many low level settings, like PID controller parameters, are available for the user.

So, OpenHR20 can give you a lot more, but… here’s the most interesting thing. People running the project found a way of connecting inside the case a small digital radio transceiver called RFM12(b). It is cheap, offers a decent range and fits into the original case of HR20. Then, you can build a “master board” that connects to USB port and allows for remote control and on-line monitoring of all your OpenHR20 valves from any device with a web browser. It works on dekstop computers, smartphones and tablets, so you can control your heating system remotely from any network device. And that’s really cool!

Aim of this tutorial

Unfortunately, the documentation for OpenHR20 (if any) is a mess, part of it being in english in the form of  a 4-year long thread on a forum, the other part is available only in german, the other is kept in project’s repo. This tutorial tries to gather all of that sources and add my own experience from setting up and running the project. I will try to give a step-by-step instructions, which will show you how to build:

• HR20 (or other supported thermostats, see below) with flashed OpenHR20 firmware, with RFM12b soldered inside, so the unit is capable of wireless communication,
• a master board built using arduino (or just ATmega328p); the board is used as a communication interface between all wireless-enabled HR20s and a computer running the web control frontend,
• a web interface for your heating system using an OpenWRT router with the master board connected.

You can of course use the whole solution building the master board using another MCU (originally, there was a master board with ATmega32) and you don’t have to use OpenWRT based device – anything that can run PHP will do. Nevertheless, that’s the configuration I’m using, it works nicely and OpenWRT router is usually always on, so it is a perfect platform for continuous gathering of statistics.

What you need to get started

You need several things to build a system as described in this tutorial:

1. A supported thermostat. Currently supported are: Honeywell HR-20, Honeywell HR-20E (it is generally the same as HR-20), Honeywell HR20-style (again, the same as HR-20, only the case is different),  Honeywell HR-25 and (some) Theromotronic devices. I’ve used only the HR20 based thermostats and got no problem with them. Currently, in Poland you can get a HR-20 for about $30.
2. Wireless radio. You need to get RFM12b modules, one per every thermostat and the additional one for the master board. There is also a version without “b” in its name. That’s an older version, which should work, but needs some small additional work, so it’s better to buy “b”. The radio comes tuned for 1 of 3 different frequencies: 433 MHz, 868MHz and 915MHz. The frequency is your choice, but remember, that you’ll need to fit an antenna inside the HR20’s case and lower frequency means longer antenna. In my case, I was using RFM12b 868 MHz. They come for about $7 apiece.
3. Some basic soldering equipment. RFM12b comes in SMD package, but it’s not very hard to solder. Nevertheless, a decent soldering iron will save you some time. No additional electronics parts are required, just some wires.
4. An ICSP programmer for AVR MCUs. There are generally 2 common ways of programming AVRs: In-System Programmer (ISP) and JTAG. ISP is much easier to use, since you can program a new microcontroller using – basically – any other microcontroller. It can be done using arduino as ISP or a cheap and simple dedicated DIY programmer, like USBtinyISP. Unfortunately, the ISP way is not possible here, you need a JTAG programmer, which is more expensive. There are many JTAG programmers, I was using an AVR Dragon, which worked flawlessly. Anyway, you need an AVR JTAG programmer and a bunch of jump wires to program ATmega169p on board of HR20.
5. A computer, which has all needed AVR developing tools. I was using Ubuntu 12.10, which has all you’re gonna need. It is (probably;) possible to do all the necessary stuff on windows too, but I didn’t test that. Everything shown here will be based on Ubuntu 12.10 and open source tools (make, avr-gcc, avrdude).
6. An arduino board or ATmega328p with external 16 MHz clock for the master board. I’ve built 3 versions of the master board: first one using arduino, next one on a breadboard using ATmega328p and the third one, based on the breadboard version, using a universal PCB. All of them worked 😉
7. A computer with USB port, capable of running simple PHP scripts. Because it fits very nicely together, I was using my home router, which runs OpenWRT. Since it is up all the time, it’s a perfect device for the control interface. You can use anything you want instead, but I’m focusing on running OpenHR20′ s interface on OpenWRT.
8. Free time. It took me 3 full days during last Christmas just to set up anything that works, but it was mainly due to the lack of documentation. That’s the part I’m trying to fix, so I hope you’ll do much better than that.

OK, that’s it for an introduction. In next parts I will explain how to solder the RFM12b radio inside HR20, how to program the MCU on board, how to build the master board and how to setup a www frontend on OpenWRT.